QuickTime 4 Reference

Settings Container Format and Guidelines

The particular atoms stored within the component's settings QT atom container are private to that component type. However, there are some guidelines that need to be followed. These include:

In all SetSettingsFromAtomContainer routines, the QT atom container belongs to the caller. The component should not dispose of the passed QT atom container.
The settings QT atom container should contain one or more top-level atoms. These top-level atoms can contain either leaf data or other atoms. Each atom has both a type (QTAtomType ) and an ID. Choosing an atom type that is mnemonic is helpful in indicating how it is used. For example, QuickTime stores video compression settings in atoms of type 'vide' . Sound compression settings are stored in 'soun' atoms. The text components use 'text' for their atom types.
Several of QuickTime's export components use the standard compression component to allow the user to configure compression settings for exported files. When one of these components is asked to return its settings atom container, the export component first requests that the standard compression component return its settings using the SCGetSettingsAsAtomContainer function described above. To the QT atom container it receives, the export component adds any of its own settings. When the export component's SetSettingsFromAtomContainer is called, the exporter calls SCSetSettingsFromAtomContainer with the passed atom container. The standard compression component extracts only those settings it expects, ignoring all other, and configures itself. The exporter then looks for its own settings in the same atom container and configures itself. This is possible because the standard compression and data exchange components both use QT atom containers to hold their settings. Because many third-party developers do the same, there must be a mechanism so that QuickTime's own top-level atom types and those of third parties don't collide. To achieve this, Apple Computer reserves all top-level atom types consisting exclusively of lowercase letters with or without numerals. For example, 'vide' is reserved by Apple, but 'Vide' is not. There is no restriction on the atom types for atoms stored within these top-level atoms.
Apple recommends that you store all of your component settings under a single top-level atom. However, there is no requirement to do so.
The data within an atom should be stored in a canonical form on all platforms. It should be always in big-endian format or always in little-endian format. Different types of atoms can be stored in different endian orders but for a single type of atom, it should always use the same order. This allows the settings to be created in the Mac OS and read in Windows or vice-versa.
In either MovieImportSetSettingsFromAtomContainer or MovieExportSetSettingsFromAtomContainer , you should not necessarily expect all atoms to be included in the atom container you receive. This allows another developer, for example, to create a settings atom container, add atoms and data for only those parts of the settings that should be changed, and then pass this incomplete atom container to the component. The component then only changes those particular settings, leaving other settings alone. QuickTime's own components use this approach.
If nil is passed for the settings to the component routines, return paramErr .
If your component does not have configurable settings, you do not need to implement the settings-related routines.